LScript User Guide
Table of Contents
Index
Errata
The following sections either missed the printing of the LScript User Guide, or
have been added to the LScript system since the manual was printed.
Inside LScript
The LScript Configuration File
The first time you execute LScript, it will create a private file that it
will use to maintain information specific to its execution and that of its
scripts. This file is called LSCRIPT.CFG, and will be created in the
directory from where LScript is executed. Since LScript is hosted LightWave
3D, that usually means the same directory where Modeler and Layout maintain
their configuration files (NewTek/Programs).
LScripts will use this file (albiet, indirectly) to house variable values
that are saved using the store() and
recall() functions. Along
with these script-owned values, LScript maintains two of its own variables.
The first, ScriptPath, is maintained by LScript to help it remember
where you keep your scripts. The second, DefaultLib, is discussed next.
By employing the library command
directly in your LScript, you can import pre-built or commonly-used LScript
user-defined procedures.
However, instead of having to duplicate often-used library directives in
each script, LScript allows you to specify default LScript libraries to be
loaded each time a script is executed. This is accomplished by adding a new
entry in the LScript configuration file (LSCRIPT.CFG) called DefaultLib.
The contents of this variable are arranged much like an MS-DOS PATH
variable. Each library entry you add to this variable needs to be
separated from others using a semi-colon (;) character. Library file
names can contain a path specification--and should if LScript cannot locate
the file at execution-time.
The DefaultLib entry needs to be added to the [LSCRIPT] area of the
configuration file.
[LSCRIPT]
ScriptPath=C:\LW\LSCRIPT
DefaultLib=C:\LW\LSLIB\LIB1.LS;C:\LW\LSLIB\LIB2.LS
...
LScript Language Structure
LSPATH Environment Variable
The ONERROR Procedure
LScript provides script programmers a means of cleaning up their execution
environment when a run-time error occurs. This is accomplished through the
use of the ONERROR() command. If LScript detects that you have defined
a procedure with this name, it will be automatically executed if a run-time
error occurs.
If the autoerror pragma has been omitted
from your script, run-time errors are defined as those that occur within the
script itself (such as attempts to access uninitialized variables). However,
errors that occur in Modeler-specific commands and functions during run-time
will also qualify for this automatic cleanup if autoerror is selected.
The batch.ls example script contains an illustration of the use
of this command. The following code snippet is taken from that script:
ONERROR
{
commandFile.close();
replyFile.close();
batchFile.close();
filedelete(tmp,"\\snii.job");
filedelete(tmp,"\\snii.rpl");
terminate(snID); // shut down ScreamerNet
}
Because the ONERROR() command does not accept parameters, variables that
you need to process at script shutdown need to be declared with global
scope (outside any user-defined procedure or main()).
The ONEXIT Procedure
ONEXIT() is identical to ONERROR() in that it is an automatic
command. However, ONEXIT(), if defined, will be called at script
termination if no run-time errors occur.
As with ONERROR(), this command does not accept parameters. Variables
that you need to process at script exit need to be declared with global scope.
Built-In Features
matchfiles
The matchfiles() function returns an array of file names (including
path) that match a specific MS-DOS file mask in the specified directory.
var files[10]; // max of ten names
...
files = matchfiles("\\","*.bat"); // get names of batch files in root directory
chdir
chdir() is one of three directory management functions LScript provides
to the script programmer. Using this function, the "working" directory of an
LScript can be altered from the directory in which the script was started.
This command also returns a character string representing the current
"working" directory of the script as a full path.
This command can be handy for launching external processes that require a
specific directory in which to execute. ScreamerNet is a perfect example
of such a process. For ScreamerNet to properly locate support files--such
as configuration files and images--it must be launched from the
NewTek/Programs directory. However, it is entirely possible that your
LScript will have begun execution in an entirely different location. The
following code snippet, illustrating the use of chdir(), solves this
particular situation:
// change the "working" directory to one required by ScreamerNet
var snDir;
var oldDir;
if((snDir = getenv("LW3D")) == nil) // is it (properly) in the environment?
oldDir = chdir("\\windows\\apps\\newtek\\programs");
else
oldDir = chdir(snDir);
snID = spawn("lwsn -2 ",
getenv("TMP"),"\\snii.job ",
getenv("TMP"),"\\snii.rpl");
chdir(olddir); // move back to our start-up directory
If the chdir() function fails to set the working directory to the
one specified, a value of nil will be returned.
mkdir
mkdir() is another directory management function. With it, an
LScript can create a new file system directory. It accepts a string
specifying the directory (with optional path), and returns a result code
(0 means no error).
rmdir
rmdir() can be used to remove an existing directory. The directory
to be removed must be completely empty for this command to succeed.
As with mkdir, this command accepts a string specifying the directory
(with optional path) to be removed, and returns a result code.
cross3d() is used to calculate the cross product of two 3D vectors.
dot3d
dot3d() is used to calculate the dot product of two 3D vectors.
cross2d
cross2d() is used to calculate the cross product of two floating-point values.
dot2d
dot2d() is used to calculate the dot product of two floating-point values.
Table of Contents
Index
© 1996 Virtual Visions, Inc.
© 1997 NewTek, Inc.